MacOS X Developer Release Notes Copyright © 2000 by Apple Computer, Inc. All Rights Reserved.
This release note describes the format for the information property list file (Info.plist) found inside application wrappers and other bundles. These files specify various information about the application or bundle that can be used at runtime. This information includes details about document types the application can edit or view (used by Finder and Cocoa); various version and copyright information that can be displayed to the user; and other static information about the app.
Although the development environment typically creates the Info.plist file, developers can and usually do add custom key/value pairs with CustomInfo.plist. This file can be created in either the XML plist format, or the older "property list" format. For apps built using the new packaging format, the resulting file will be XML.The new format adds the document-type information necessary for the new document-based application architecture in the Application Kit. It also puts in place the information the Finder needs. Applications can deal better with HFS and be better prepared for future releases if they adopt the new format. The new standard About panel also makes use of some of these keys.
CFBundleVersion should be a CFString. The value is app-specific, but if the traditional MacOS versioning format is used (1.2.3d6), then the version number can be retrieved properly with the CFBundleGetVersionNumber() function.
CFPreferences will now read/write app-specific preferences using the CFBundleIdentifier key, if provided, instead of just the app name. This allows for more unique names.
There have been some changes/clarifications on the uses of some keys. For instance, CFBundleName is now treated as the "short" name, displayed in the menu bar and in the standard Cocoa about panel.
The biggest change in the information property list format since DP3 is the introduction of an "abstract type" for any data found in documents or on the pasteboard. Abstract types have corresponding concrete types, such as a filename extension or an OSType (4-byte identifier). Concrete types are ways that an abstract type is encoded in various file systems or persistent formats. This notion improves general application interoperability by removing the current dichotomy between the pasteboard type system and the filename-extension type system.
Abstract types may want to contain a copyright to ensure uniqueness. Developers will need to register their concrete types.
Applications that declare types can declare their role in relation to the type:
The following tables supply details of the new format. Note that the Info.plist files are extensible by design, and thus other subsystems may define additional keys not specified here. In addition to the Info.plist file, a bundle can contain a localizable resource file called InfoPlist.strings. Some of the Info.plist keys are allowed to be put in this file so they can be localized. Localized keys may or may not also be present in the Info.plist itself, but this is not required.
For examples of Cocoa applications that provide CustomInfo.plist files, see the TextEdit or Sketch examples. For a Carbon application example, see SimpleText.
Most Info.plist keys are not required. Where it makes sense, there are usually fall-backs for missing keys. For instance, if the CFBundleExecutable key is missing, CFBundle will look for an executable with the same name as the bundle. The absence of other keys will just mean that the feature that key controls will not be turned on (ie the application will not claim any document types if CFBundleDocumentTypes is missing).
The following keys are defined and used by either CFBundle, the Finder, or the Cocoa frameworks. Keys relevant only to Cocoa typically start with "NS". Keys that are often put into the localized InfoPlist.strings file are marked with an asterisk (*).
| Key | Old Key | Value Description |
|---|---|---|
| CFBundleExecutable | NSExecutable | Name of the file holding the executable code for the bundle. (without any platform-specific file extension such as ".exe"). |
| <obsolete> | NSExtensions | Deprecated , with status-quo semantics. If an CFBundleDocumentTypes or NSTypes field exists, this field is ignored. |
| CFBundleIconFile | NSIcon | Name of the image file for the application icon, for instance "Preview.icns". Assumed to exist in the bundle. If no extension is provided, a platform-specific extension (on Mac OS X, ".icns") is assumed. |
| NSMainNibFile | NSMainNibFile | Name of the main nib file for an application |
| NSPrincipalClass | NSPrincipalClass | Name of the principal class for a bundle. |
| NSServices | NSServices | Definition of services provided by an application. |
| CFBundleInfoDictionaryVersion | NSInfoPlistVersion | Version number for the info plist format. New plists should be version 6.0. |
| CFBundleVersion | <none> | App-specific version string (such as 1.2.3d6). The value of this string typically changes between different builds. |
| CFBundleIdentifier | <none> | A Java package style name (like "com.foo.MyBundle") which can be used to uniquely identify the bundle and locate its CFBundleRef at runtime. CFPreferences uses this key, if provided, as the domain name to store app-specific user preferences under. |
| CFBundleDevelopmentRegion | <none> | The native region (or language) of this bundle. This region will always be used as a backstop for finding resources that are not located in the user's preferred language. |
| CFBundleName (*) | NSHumanReadableName | The short display name for the bundle. This key is usually found in the InfoPlist.strings file since it is usually localized. Use this key to indicate what name should be displayed in the menu bar when your app is active. |
| CFBundlePackageType | NSMacOSType | The MacOS-style four-letter type of the bundle (eg "APPL" for applications, "FMWK" for frameworks, "BNDL" for generic bundles or any other code for specific types of bundles). |
| CFBundleSignature | NSMacOSCreator | The MacOS-style four-letter creator code for the bundle. |
| CFBundleShortVersionString (*) | NSAppVersion | A short string with version info for the bundle. CFBundleVersion is more useful for actual version identification, but this string might be shown to the user. This key is usually found in the InfoPlist.strings file since it is usually localized. |
| CFBundleGetInfoString (*) | <none> | The string for Get Info panels. |
| CFBundleGetInfoHTML (*) | <none> | This can be used instead of CFBundleGetInfoString for richer content. |
| NSHelpFile | NSHelpFile | Name of the main help file for Cocoa applications. |
| CFBundleDocumentTypes | NSTypes | Information about document types the bundle knows about. (See below.) |
| CFBundleURLTypes | <none> | Information about URL schemes the bundle can handle. (See below.) |
| NSHumanReadableCopyright (*) | NSHumanReadableCopyright | The copyright string for the app (used in Cocoa standard about panels. |
| <obsolete> | NSHumanReadableShortName | This key is no longer used. |
| <obsolete> | NSHumanReadableCompleteName | This key is no longer used. |
The CFBundleDocumentTypes property is an array of dictionaries. Each dictionary describes a document type. Each document type dictionary may have the following keys. The value of the CFBundleTypeName key can appear as a key in the InfoPlist.strings file in order to provide a localized name for the type.
| Key | Old Key | Value Description |
|---|---|---|
| CFBundleTypeName | NSName | The abstract name of this data type. It is used when this data is on the pasteboard. It should contain a trademarked name to ensure uniqueness. Must be present for this type to be valid. Note that for system types you can use one of the pasteboard variable names as the NSName value such as NSStringPboardType (see below for full list). |
| CFBundleTypeIconFile | NSIcon | The name of the image file for this type. (The file is assumed to be located in the bundle.) Assumed to exist in the bundle. If no extension is provided, a platform-specific extension (on Mac OS X, ".icns") is assumed. |
| CFBundleTypeExtensions | NSUnixExtensions & NSDOSExtensions | An array of file suffixes used to encode this type. It is case-insensitive. The first suffix is used as the extension for newly created files. |
| CFBundleTypeOSTypes | NSMacOSTypes | An array of four-byte MacOS codes used to encode this type. The first code is used as the OSType for newly created files. |
| CFBundleTypeMIMETypes | NSMIMETypes | An array of MIME types used to encode this type. |
| CFBundleTypeRole | NSRole | A string indicating the role this application plays for this type: one of Editor, Viewer or None (see "Roles" above). If absent, the role is assumed to be "Editor". |
| NSDocumentClass | NSDocumentClass | The NSDocument subclass used to instantiate instances of the document. |
| NSExportableAs | NSExportableAs | An array of other types that documents of this type can be exported as. This is used to specify write-only types. |
As mentioned above, theCFBundleTypeName can have some special values from the symbol names for common pasteboard types. These come from NSPasteboard.h in the AppKit framework. The allowable special values for the CFBundleTypeName are:
The CFBundleURLTypes property is an array of dictionaries. Each dictionary describes an URL type. Each document type dictionary may have the following keys. The value of the CFBundleURLName key can appear as a key in the InfoPlist.strings file in order to provide a localized name for the type. The exact use and support for this key is still under discussion.
| Key | Value Description |
|---|---|
| CFBundleURLName | The abstract name of this URL type. |
| CFBundleURLIconFile | The name of the image file for this type. (The file is assumed to be located in the bundle.) This name should not include any file extension indicating the image type (such as "icns" or "tiff" or "ico"). The appropriate image type for the platform will be looked for. |
| CFBundleURLSchemes | An array of URL schemes that this URL type corresponds to. |